Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds.fmt / cvs.man < prev next >

Wrap

Text File | 1991-12-12 | 55.1 KB | 1,387 lines

CVS UNKNOWN MANUAL SECTION CVS NNAAMMEE cvs - Concurrent Versions System SSYYNNOOPPSSIISS ccvvss [ _c_v_s__o_p_t_i_o_n_s ] _c_v_s__c_o_m_m_a_n_d [ _c_o_m_m_a_n_d__o_p_t_i_o_n_s ] [ _c_o_m_m_a_n_d__a_r_g_s ] DDEESSCCRRIIPPTTIIOONN ccvvss is a front end to the rrccss(l) revision control system which extends the notion of revision control from a collec- tion of files in a single directory to a hierarchical col- lection of directories consisting of revision controlled files. These directories and files can be combined together to form a software release. ccvvss provides the functions necessary to manage these software releases and to control the concurrent editing of source files among multiple software developers. The following list summarizes some of the strong points of ccvvss: o+ Only a single copy of the master sources exist. This copy is called the source ``repository'' and, through administrative actions, contains all the information to extract previous software releases at any time based on either a symbolic revision tag, or a date in the past. o+ Individual software developers check out private copies of the sources into their personal work space. These private sources can be edited at any time and checked back into the source repository as a permanent change. ccvvss takes special care to ensure that a file is up-to- date with the current revision in the source repository before allowing it to be added as a permanent change. o+ There is a facility for software developers to bring their private copies of the sources up-to-date with the currently checked in revisions, while at the same time preserving any modifications that have been made to their private sources. This allows multiple developers to be concurrently working on the same source files without regard for what the other guy is doing. Note that this is the biggest change from the way most other revision control systems, like RCS or SCCS work, which allow only one developer to ever be changing a file, since the file must be checked out as ``locked'' for the exclusive use of that person. ccvvss instead never applies an RCS lock to a checked out file until the moment before it is to be checked back in as a per- manent change. Concurrency checks are performed on the soon-to-be checked in file and the file must be up-to- Sprite v1.0 20 July 1989 1 CVS UNKNOWN MANUAL SECTION CVS date before it can be made permanent. In this way, ccvvss allows individuals the freedom to change any file at will, and provides the tools necessary to point out, if not resolve, any conflicts that may be generated by allowing this extra, and necessary, freedom. o+ ccvvss has direct support for tracking source releases from third-party vendors. The cchheecckkiinn(l) program is used to initially setup the source repository. The branch support of RCS is used to build the vendor release as a branch off the main (local) RCS trunk. Once this is done, developers can check out files and make local changes to the vendor's source distribution. The act of checking in a local change to a vendor's source distribution moves the RCS branch from tracking the third-party vendor's release to the main (local) RCS trunk so that the local version of the file is used forever more. When a new version of the vendor's source distribution (or even a minor version consisting of a small subset of files) arrives, the cchheecckkiinn program is used again to add the new vendor release to the already existing source repository. For files that have not been changed locally, the new file from the vendor becomes the current revision. For files that have been modi- fied locally, cchheecckkiinn warns that the file must be merged manually with the new vendor release. The jjooiinn command of ccvvss is a useful tool that aids this manual merge process (see below). o+ A vendor release or a local release can be given a sym- bolic tag name that is stored directly in the RCS files. This tag can be used at any time in the future to get an exact copy of any previous release. With equal ease, one can also extract an exact copy of the source files as of any arbitrary date in the past as well. o+ All changes that are made to the source repository are carefully logged in a file, notesfile, or news data- base, which can be used to produce release notices. ccvvss can be configured to send log updates through one or more filter programs, based on a regular expression match on the directory that is being changed. This allows multiple related or unrelated projects to exist within a single ccvvss source repository tree, with each different project sending their checkin reports to a unique log device for the project. o+ There is support for a simple, yet powerful, ``module'' database. This database can be used to apply names to Sprite v1.0 20 July 1989 2 CVS UNKNOWN MANUAL SECTION CVS collections of directories and files as a matter of convenience when checking out smaller pieces of a larger software distribution. This allows one to checkout the ``diff'' program, for example, without ever requiring the knowledge that the sources to ``diff'' actually reside in the ``bin/diff'' directory. The module database also has limited support for an aliasing capability. This is useful for programs that share sources from completely disjoint directories. The aliasing feature can also be used to limit a named release to a certain collection of directories and files, to only work with pieces of the source found in the entire source repository. o+ There is direct support for determining which files have changed since a previous release, or from a par- ticular date. As well, ccvvss can create a ppaattcchh(l) for- mat output file which can be used to bring a previously released software distribution current with the newest release. One can create a patch file between two tagged revisions, between a revision and some date in the past, between two dates, or between a date or revi- sion and the current ``head'' revision. The remainder of this manual page will document how all these actions can be done using the ccvvss program. OOPPTTIIOONNSS ccvvss accepts a number of options that override the current setting of the recognized environment variables. --rr Checks out files read-only. Same effect as if the CVSREAD environment variable is set. --ww Checks out files read-write (default). Overrides the setting of the CVSREAD environment variable. --vv Outputs version and copyright information for ccvvss, then exits. --dd _C_V_S__r_o_o_t__d_i_r_e_c_t_o_r_y Use _C_V_S__r_o_o_t__d_i_r_e_c_t_o_r_y as the root directory pathname of the master RCS source repository. Overrides the setting of the CVSROOT environment variable. --bb _b_i_n_d_i_r Use _b_i_n_d_i_r as the directory to find RCS programs within. Overrides the setting of the RCSBIN environ- ment variable. --ee _e_d_i_t_o_r Sprite v1.0 20 July 1989 3 CVS UNKNOWN MANUAL SECTION CVS Use _e_d_i_t_o_r for editing revision log information. Over- rides the setting of the EDITOR environment variable. --HH Displays usage information about the specified _c_v_s__c_o_m_m_a_n_d without actually executing said command. UUSSAAGGEE A _c_v_s__c_o_m_m_a_n_d must be specified to ccvvss which drives the specific release control function that is performed. Each ccvvss command accepts options and arguments unique to the com- mand. The usage statements for each command can be displayed by specifying the --HH option to the command. The available commands are listed below along with a description of their function. Command options unique to the command are described in this section with the command description. Common command options are described fully in the following section. cchheecckkoouutt [--QQqqllffnnpp] [--cc] [--rr _t_a_g|--DD _d_a_t_e__s_p_e_c] _m_o_d_u_l_e_s... Checks out the source files defined by _m_o_d_u_l_e_s. This command is used to get a private copy of the current sources that can be edited and processed by most of the other ccvvss commands. cchheecckkoouutt must be done before many of the other ccvvss commands are used, since most of them operate on checked out sources. Depending on the _m_o_d_u_l_e_s specified, cchheecckkoouutt may recur- sively create directories and populate them with the appropriate source files. These source files can then be edited at any time (regardless of whether other software developers are editing their private copies of the sources), updated to include new changes checked into the source repository, or committed as a permanent change to the RCS repository. Note that cchheecckkoouutt is used to create directories. The top-level directory created is always added to the working directory where cchheecckkoouutt is invoked, and usu- ally has the same name as the specified _m_o_d_u_l_e. In the case of a _m_o_d_u_l_e alias, the created sub-directory may have a different name, but you can be sure that it will be a sub-directory, and that cchheecckkoouutt will show the relative path leading to each file as it is extracted into your private work area, unless the --QQ option is specified. Running cchheecckkoouutt on a directory that was already built by cchheecckkoouutt is also OK. This has the same effect as specifying the --dd option to the uuppddaattee command described below. Sprite v1.0 20 July 1989 4 CVS UNKNOWN MANUAL SECTION CVS The --cc option ``cat''s the module file, sorted, to the standard output, and does not cause any files or direc- tories to be checked out. ccoo can be specified instead of cchheecckkoouutt to save some typing. See the MODULES section below for a complete description of modules. uuppddaattee [--QQqqllffpp] [--dd] [--rr _t_a_g|--DD _d_a_t_e__s_p_e_c] _f_i_l_e_s... After cchheecckkoouutt is run, directories and files have been extracted from the source repository for your personal editing. At any time that is convenient in your development process, the uuppddaattee command can be run _f_r_o_m _w_i_t_h_i_n _t_h_e _d_i_r_e_c_t_o_r_y _t_h_a_t _c_o_n_t_a_i_n_s _t_h_e _c_h_e_c_k_e_d _o_u_t _s_o_u_r_c_e_s to bring those sources current with any revi- sions that have been checked into the source repository since they were last checked out or uuppddaatteed. Normally, uuppddaattee brings the current directory up-to- date, then descends any sub-directories, bringing them up-to-date as well. This can be overridden by specify- ing a list of files that should only be updated, or by using the --ll option which causes uuppddaattee to only process the current directory, ignoring any sub-directories. If any special options were initially specified to cchheecckkoouutt when the source were initially checked out, these exact options should be specified to uuppddaattee as well to keep the sources consistent with the way they were originally checked out. For example, checking out sources by specifying the ``--rr VV11__00'' option will check out the revisions associated with the VV11__00 release tag. A subsequent uuppddaattee that does _n_o_t specify this exact --rr option as well will revert to updating the sources with the current revisions as stored in the source reposi- tory, rather than those revisions associated with the VV11__00 release. If the --dd option is specified then uuppddaattee will update your source tree with any new directories that have been added to the repository. For a complete description of the algorithm that uuppddaattee uses to bring your source up-to-date, refer to the CCOONN-- FFLLIICCTT RREESSOOLLUUTTIIOONN section below. ccoommmmiitt [--QQqqffnn] [-a] [--mm '_l_o_g__m_e_s_s_a_g_e'] [-- rr _r_e_v_i_s_i_o_n] [_f_i_l_e_s...] At any point, changes that you have made to your private copies of the sources may be ccoommmmiittted to the source repository as a permanent change. ccoommmmiitt does not do a recursive ccoommmmiitt, so each individual directory Sprite v1.0 20 July 1989 5 CVS UNKNOWN MANUAL SECTION CVS must be checked in separately, even if the changes were related. ccoommmmiitt verifies that the selected files are up-to-date with the current revisions in the source repository and will abort without committing if any of the specified files must be made current first with the uuppddaattee com- mand. With the --aa option, all relevant files of the current directory are examined. ccoommmmiitt is careful to only check in those files that have really changed. Note that ccoommmmiitt does not uuppddaattee the out-of-date files for you, but rather leaves that for you to do when the time is right. An RCS identification string ($Id) must exist in the modified files that are to be checked in. If the iden- tification string cannot be found in any of the files, ccoommmmiitt will prompt you for verification before proceed- ing. This prompt is bypassed if the --ff option has been specified. When all is well, an editor is invoked for the purpose of entering a log message that will be written to one or more logging programs and placed in the RCS source repository file. The log message may be specified on the command line with the --mm option, thus suppressing the editor invocation. ccii can be specified instead of ccoommmmiitt to save some typ- ing. ddiiffff [_r_c_s_d_i_f_f__o_p_t_i_o_n_s] [_f_i_l_e_s...] Your checked out files can be diffed against the origi- nal revisions they were based upon with the ddiiffff com- mand. See rrccssddiiffff(l) for a list of accepted options. If no files are specified, ddiiffff will only ``diff'' those files in the current directory that are different than the checked out revision (i.e. ones that _y_o_u have changed), or that are different than a specified revi- sion. If files are specified, only those files are diffed. Two revisions may be specified as well. In which case your private sources are not diffed at all. Instead, the two revisions specified are diffed. lloogg [_r_l_o_g__o_p_t_i_o_n_s] [_f_i_l_e_s...] To display revision log information equivalent to the rrlloogg(l) program, the lloogg command is used. See rrlloogg(l) for a list of accepted options. If no files are speci- fied, lloogg will run an rrlloogg (with the arguments asa specified) on every file under ccvvss control in the Sprite v1.0 20 July 1989 6 CVS UNKNOWN MANUAL SECTION CVS current directory. If files are specified, the log information of only those files is displayed. ssttaattuuss [_f_i_l_e_s...] Displays three lines of information for each of its argument files, one for the user file (line 1), one for the newest RCS file showing the current ``head'' revi- sion number (line 3), and one for the RCS file both derive from showing the date it was last updated (line 2). aadddd [--mm '_m_e_s_s_a_g_e'] _f_i_l_e_s... To permanently create a new file or directory in the RCS source repository, the aadddd command is used. The files or directories specified to aadddd must already exist in the current directory (which must have been created with the cchheecckkoouutt command). For adding a whole new directory hierarchy to the source repository that was received from a third-party vendor, see the cchheecckkiinn(l) program for how to do this. If the argument refers to an immediate sub-directory, the directory is created at the correct place in the RCS source repository and the necessary ccvvss administra- tion files are created within the argument directory. It is not considered an error if the RCS source reposi- tory directory already exists. Thus, to add a direc- tory to your private sources that was created after you had done your cchheecckkoouutt of the sources, you can do the following: eexxaammppllee%% mmkkddiirr nneeww__ddiirreeccttoorryy eexxaammppllee%% ccvvss aadddd nneeww__ddiirreeccttoorryy eexxaammppllee%% ccvvss uuppddaattee nneeww__ddiirreeccttoorryy For each added file, a description of the file's pur- pose is read from the terminal in RCS fashion, unless the --mm option is specified, in which case the argument _m_e_s_s_a_g_e is used instead. This description will become a permanent part of the created RCS file. The added files are not placed in the RCS source repo- sitory until they are ccoommmmiittted as a permanent change. Doing an aadddd on a file that has been removed with the rreemmoovvee command will resurrect the file, unless it has already been ccoommmmiittted. rreemmoovvee _f_i_l_e_s... Marks the specified files as removed on purpose from the current directory in the source repository. The specified files must no longer exist in the current directory when the rreemmoovvee command is issued. The files Sprite v1.0 20 July 1989 7 CVS UNKNOWN MANUAL SECTION CVS are not actually removed until they are ccoommmmiittted, at which point their respective RCS files in the source depository are _m_o_v_e_d into the _A_t_t_i_c directory within the source repository. To restore a committed removed file to the present version requires an administrator to physically _m_o_v_e the RCS file out of the _A_t_t_i_c and back into its parent directory. jjooiinn [--QQqqff] [--rr _t_a_g|--DD _d_a_t_e__s_p_e_c] _f_i_l_e_s... The intended purpose of the jjooiinn command is to perform the logical merge of a new vendor release installed with the cchheecckkiinn(l) command with locally modified files from a previous vendor release. The cchheecckkiinn program will inform you that a vendor file has been locally modified and it is up to _y_o_u to resolve the two branches of development (local and vendor) into a uni- fied revision that will be ccoommmmiittted as a permanent change to the source repository on the main (local) trunk. The jjooiinn command will usually be used with the --rr option to specify the vendor tag that is to be merged with the local changes. This merge is handled by RCS and the resultant file is placed in the current directory (within your private work space) and any con- flicts during the merge are displayed. After correcting any conflicts during the merge, ccoommmmiitt the joined file as usual with a modified file, and the result (with a bit of work, perhaps) should be a work- ing combination of the local changes and the vendor changes. iinnffoo [--ff] [--rr _t_a_g|--DD _d_a_t_e__s_p_e_c] _f_i_l_e_s... The iinnffoo command gives a brief summary of the state of your checked out files. Its output is similar to that of the uuppddaattee command. See the CCOONNFFLLIICCTT RREESSOOLLUUTTIIOONN section for details. If no arguments are given iinnffoo will print the state of all files in the current direc- tory, otherwise it will print the state of the speci- fied files. IInnffoo is not recursive. There is a small difference in the meaning of the CC notation between the iinnffoo and uuppddaattee commands. IInnffoo will print a CC in front of any file that has been modified both locally and in the repository. UUppddaattee will only print a CC if a merge of the two versions produces a conflict. The following commands do their work entirely within the RCS source repository and, as such, do not require that a cchheecckkoouutt be done first. These commands are usually of interest only to the person responsible for the release pro- cedures of a software package. See the MMOODDUULLEE SSUUPPPPOORRTT sec- tion below for a full description of what a _m_o_d_u_l_e is. Sprite v1.0 20 July 1989 8 CVS UNKNOWN MANUAL SECTION CVS _m_o_d_u_l_e_s... ppaattcchh [--QQqqllff] [--ss|--tt] [--rr _t_a_g|--DD _d_a_t_e__s_p_e_c [--rr _t_a_g|-- DD _d_a_t_e__s_p_e_c]] Builds a Larry Wall format ppaattcchh(l) file between two releases that can be fed directly into the ppaattcchh pro- gram to bring an old release up-to-date with the new release. The diff output is sent to the standard out- put device. Note that any combination of one or two revisions or dates may be specified. If only one revi- sion or date is specified, the ppaattcchh is made between that revision or date and the current ``head'' revi- sions in the RCS file. Note that if the software release that is being ppaattcchhed is contained in more than one directory, then it may be necessary to specify the --pp option to the ppaattcchh(l) com- mand when patching the old sources, so that ppaattcchh(l) is able to find the files that are located in other direc- tories. If the --ss option is specified, a patch file is not pro- duced. Instead, a description of the changed or added files between the two releases is sent to the standard output device. This is useful for finding out, for example, which files have changed between two dates or revisions. If the --tt option is specified, a diff of the top two revisions is sent to the standard output device. This is most useful for seeing what the last change to a file was. ttaagg [--QQqqllffnn] [--dd] [--rr _t_a_g|-- DD _d_a_t_e__s_p_e_c] _s_y_m_b_o_l_i_c__t_a_g _m_o_d_u_l_e_s... Sources in the repository can have a symbolic tag asso- ciated with them. This allows one to ``snapshot'' the current sources when the software freeze date of a pro- ject arrives, and as bugs are fixed after the freeze date, only those changed sources that are to be part of the release need be re-tagged. The symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribution. The functionality provided with the cchheecckkoouutt and uuppddaattee commands allow one to extract an exact copy of this release at any time in the future, regardless of whether files have been aadddded or rreemmoovveed since the release was ttaaggged. So in general, these symbolic names of software distributions should not be removed, but the --dd option is provided as a means to remove completely obsolete symbolic names if necessary (as might be the case for an Alpha release, Sprite v1.0 20 July 1989 9 CVS UNKNOWN MANUAL SECTION CVS say). It is also possible to only tag files that already contain a certain tag. This method would be used to rename a tag - tag only the files with the old tag, then delete the old tag leaving the new tag which would tag the exact same files as the old tag. CCOOMMMMAANNDD OOPPTTIIOONNSS The following options are common to more than one of the ccvvss commands, and are explained in detail here once, for brev- ity. --QQ Causes the command to be _r_e_a_l_l_y quiet. --qq Causes the command to be somewhat quiet. --ll Causes the command to not be recursive. Only the specified directory will be processed. --ff Forces the specified tag to match. Normally, when a tag is specified with the --rr option and the RCS file does not contain the tag, the ``head'' revision for the RCS file is returned. When the --ff option is specified, any RCS file that does not contain the specified tag is ignored. This is useful for extracting an exact copy of a previously tagged release. --nn Causes the command _n_o_t to run any cchheecckkoouutt/ccoommmmiitt/ttaagg program as specified in the modules database. --pp On cchheecckkoouutt or uuppddaattee, prune directories that are empty after being updated. This is useful for extracting an exact copy of a previously release, especially when combined with the --ff option. --rr _t_a_g Causes the command to use the revision specified by the _t_a_g argument instead of the usual ``head'' revision. The _t_a_g can be either a symbolic or numeric tag, in RCS fashion, except in the case of the ccoommmmiitt command, in which case the _t_a_g must be a numeric one. Specifying the --qq option along with the --rr option is often useful, to suppress the warning messages when the RCS file does not contain the specified tag. --DD _d_a_t_e__s_p_e_c Causes the command to use the revision that was checked in at or before the specified _d_a_t_e__s_p_e_c argument. The _d_a_t_e__s_p_e_c is a single argument, free form date descrip- tion specifying a date in the past. This option implies the --ff option. See the EEXXAAMMPPLLEESS section for useful examples of how the --DD option can be used. Sprite v1.0 20 July 1989 10 CVS UNKNOWN MANUAL SECTION CVS CCOONNFFLLIICCTT RREESSOOLLUUTTIIOONN The algorithm used by cchheecckkoouutt and uuppddaattee is described in this section. The output generated, unless the --QQ option is specified, consists of the following lines to describe exactly how your private sources are being brought up-to- date with the RCS source repository. UU _f_i_l_e The specified file was copied directly out of its respective RCS file from the source repository. This is done because the condition of your user file matches one of the following: o+ The user file did not exist in your private sources, whether it was because you removed it, or because someone added it to the source repository. o+ The file did exist, but you did not change it and a different revision was matched in the RCS file, be it by the default ``head'' match, or via the --rr or --DD options. MM _f_i_l_e The specified file has been modified locally by you. Use the ddiiffff command to see the actual changes that you have made. AA _f_i_l_e The specified file has been added to your private copy of the sources, and will be added to the RCS source repository when the file is ccoommmmiittted. This is a rem- inder to you that the file needs to be committed. RR _f_i_l_e The specified file has been removed from your private copy of the sources, and will be removed from the RCS source repository when the file is ccoommmmiittted. This is a reminder to you that the file needs to be committed. CC _f_i_l_e_s The specified file was modified locally by you, and while doing the uuppddaattee, it was determined that a later revision had been checked into the respective RCS file. As a result, ccvvss performs an rrccssmmeerrggee(l), which com- bines the changes made to the RCS file with the changes that you have made to your version of the file. If there were any lines in conflict during the merge (i.e. the other developer changed the same line that you have changed), then the CC is displayed to show that the file must be manually corrected. This merge process delimits the lines in conflict using lines beginning with ``>>>>>>>'' and ``<<<<<<<'', so it is easy to find the conflicts within your merged file. Sprite v1.0 20 July 1989 11 CVS UNKNOWN MANUAL SECTION CVS Note that your original, modified file is preserved in a backup file within the same directory that the file existed. The backup file has the form ``..##_f_i_l_e.._v_e_r_s_i_o_n'', where the _v_e_r_s_i_o_n is the RCS revi- sion that your modified file was based upon. Note that some systems automatically purge files that begin with ..## if they have not been accessed in roughly three days. Thus, if you intend to keep a copy of your ori- ginal file, I strongly suggest that it be renamed. If the merge process proceeded without any conflicts, an MM is displayed instead of a CC. It is still a wise idea to ddiiffff(1) the original version before the merge, contained in the backup file, with the merged version to verify that the merged changes make sense with your changes. MMOODDUULLEE SSUUPPPPOORRTT The cchheecckkoouutt, ppaattcchh, and ttaagg commands all accept _m_o_d_u_l_e names as arguments. The module database is stored as an nnddbbmm(3) format database within the CVSROOT.adm directory of your CVSROOT source repository. The remainder of this sec- tion considers how the cchheecckkoouutt command operates on the modules database. The operations for the other commands that use the database are similar, except that they do not create any files or directories in your work space, as cchheecckkoouutt does. The above commands search the module database for each module argument. If the module database does not exist, or if the argument does not have a matching key in the module database, the argument is processed as follows: 1. The value of the CVSROOT environment variable is prepended to the argument to form a full path name. 2. If the full path name does not exist, either as a directory or as a file with an RCS ,,vv extension, the argument module cannot be resolved and the command con- tinues, processing any remaining argument modules. 3. If the full path name refers to a directory, the direc- tories leading up to the directory are created, start- ing from the current working directory, and the direc- tory is populated with the correct files, ready for your editing satisfaction. If available, and the --ll option was not specified, sub-directories are created and populated as well, until the entire directory hierarchy of the specified module argument is recon- structed in your work space. 4. If the full path name, combined with an RCS ,,vv suffix Sprite v1.0 20 July 1989 12 CVS UNKNOWN MANUAL SECTION CVS exists, only that file is extracted. The directories leading up to where the argument module resides are created, if necessary, and the leaf directory is popu- lated with the single source file. It should be clear from reading the above algorithm that the module database is not required to extract or process whole directory hierarchies, or even individual files. However, the addition of the module database allows a high degree of flexibility to be added to the structure or naming of pieces of software within the CVSROOT source hierarchy. The easi- est way to demonstrate the usefulness of the module database is by example. And so, one follows: Sprite v1.0 20 July 1989 13 CVS UNKNOWN MANUAL SECTION CVS # # Sample CVS Modules file # # Three different line formats are valid: # key -a aliases... # key [options] directory # key [options] directory files... # # Where "options" are composed of: # -i prog Run "prog" on checkin of files # -o prog Run "prog" on "checkout" of files # -t prog Run "prog" on tagging of files # # Convenient aliases world -a . # CVSROOT.adm support CVSROOT -i /usr/local/bin/mkmodules CVSROOT.adm CVSROOT.adm -i /usr/local/bin/mkmodules CVSROOT.adm modules -i /usr/local/bin/mkmodules CVSROOT.adm modules loginfo -i /usr/local/bin/mkmodules CVSROOT.adm loginfo # The "sys" entry exists only to make symbolic links after checkout sys -o sys/tools/make_links sys # Sub-directories of "bin" awk bin/awk csh bin/csh diff bin/diff make bin/make sed bin/sed sh bin/sh # Programs that live in "bin" cat bin Makefile cat.c chgrp bin Makefile chgrp.c chmod bin Makefile chmod.c cmp bin Makefile cmp.c cp bin Makefile cp.c date bin Makefile date.c dd bin Makefile dd.c The format of the _m_o_d_u_l_e_s file is also described in the above example. The --aa option in the database indicates that the key is an alias, and that the right-hand side of the alias is to be interpreted by the command _e_x_a_c_t_l_y as if it had been specified as arguments on the command line for the command. The --oo option indicates that the specified program is to be run on cchheecckkoouutt. The key for the entry is passed as the sole argument to the program. The --ii option indi- cates that the specified program is to be run on ccoommmmiitt. Sprite v1.0 20 July 1989 14 CVS UNKNOWN MANUAL SECTION CVS The full pathname of the respective source repository direc- tory is passed as the sole argument to the program. The --tt option indicates that the specified program is to be run on ttaagg. The key for the entry is passed as the sole argument to the program. As an example, the command eexxaammppllee%% ccvvss cchheecckkoouutt aawwkk will create the ``awk'' directory in your current working directory, if necessary, and populate it with the current revisions of the files in the ``$CVSROOT/bin/awk'' direc- tory. The command eexxaammppllee%% ccvvss cchheecckkoouutt ddaattee will create the ``date'' directory and populate with exactly the two files ``Makefile'' and ``date.c'' from the ``$CVSROOT/bin/awk'' directory. VVEENNDDOORR BBRRAANNCCHH SSUUPPPPOORRTT The branch support of RCS is used to provide a convenient method of tracking the changes made to a vendor's source distribution. When a source distribution is received from a vendor, the first step is to run the cchheecckkiinn(l) program to place the vendor's files under CVS control. cchheecckkiinn(l) arranges that the RCS files produced from the vendor's source distribution are initially setup to track the 1.1.1 branch of the RCS file. When a ccoommmmiitt is done to one of these files, making permanent some local change, the RCS file is changed to track the normal ``trunk'' branch, con- tinuing the local changes to the vendor's sources. When a new version of the vendor's source distribution is received, cchheecckkiinn is used again to add the new files to CVS. cchheecckkiinn again adds the files to the (now already existing) 1.1.1 branch of the RCS file. This time, however, cchheecckkiinn issues a warning when a new version of a locally modified file is updated by the vendor's source distribution. It is your responsibility to then use the jjooiinn command of ccvvss to merge the vendor's changes with your local changes. See the description of the jjooiinn command above. The --rr and --DD options of the cchheecckkoouutt and uuppddaattee commands work ``as expected'' with the vendor branch support. In particular, the --DD option to check out based on a date in the past follows the current default branch to find a match for the specified date. If a match cannot be found on the default branch, the 1.1.1 vendor branch is searched. This allows checking out based on a date to work regardless of when local changes are made to the file. Sprite v1.0 20 July 1989 15 CVS UNKNOWN MANUAL SECTION CVS LLOOGGGGIINNGG SSUUPPPPOORRTT When ccoommmmiittting a change to the source repository, a confi- gurable logging support file, _l_o_g_i_n_f_o, is consulted in the $CVSROOT/CVSROOT.adm directory. An example of the file is as follows: # The "loginfo" file is used to control where "cvs commit" # log information is sent. The first entry on a line is a # regular expression which is tested against the directory # that the change is being made to, relative to the # $CVSROOT. If a match is found, then the remainder of the # line is a filter program that should expect log information # on its standard input. # # The filter program may use one and only one % modifier (ala # printf). If %s is specified in the filter program, a brief # title is included (enclosed in single quotes) showing the # modified file names. # # If the repository name does not match any of the regular # expressions in this file, the "DEFAULT" line is used, if it # is specified. # DEFAULT /usr/local/bin/nfpipe -t %s utils.updates ^diag /usr/local/bin/nfpipe -t %s diag.updates ^local /usr/local/bin/nfpipe -t %s local.updates ^perf /usr/local/bin/nfpipe -t %s perf.updates ^sys /usr/local/bin/nfpipe -t %s kernel.updates In addition, ``ALL'' can be specified as a special regular expression which always matches, but does not change the behaviour of when the ``DEFAULT'' branch is taken. All matches for the regular expression are executed. This log- ging feature allows for multiple groups and logging programs to share a single CVS source repository. EEXXAAMMPPLLEESS Using the example _m_o_d_u_l_e_s and _l_o_g_i_n_f_o files shown above, this section shows some sample commands and describes their functions. eexxaammppllee%% ccvvss cchheecckkoouutt ccsshh eexxaammppllee%% ccdd ccsshh eexxaammppllee%% mmaakkee This command retrieves the current revision of the ``csh'' sources and places them within the ``csh'' directory. The ``make'' command within that directory will then build the ``csh'' executable. eexxaammppllee%% ccvvss cchheecckkoouutt --rrSSuunnOOSS ccsshh eexxaammppllee%% ccdd ccsshh Sprite v1.0 20 July 1989 16 CVS UNKNOWN MANUAL SECTION CVS eexxaammppllee%% mmaakkee These commands get the current SunOS revision of ``csh'' and builds the executable. eexxaammppllee%% ccvvss cchheecckkoouutt ddaattee eexxaammppllee%% ccdd ddaattee eexxaammppllee%% mmaakkee ddaattee These commands checkout the current revision of the ``date'' command, along with the Makefile that is required to build the ``date'' executable. The ``make'' command includes the target ``date'', since this Makefile is used to build much more than just ``date'' by default. eexxaammppllee%% ccvvss cchheecckkoouutt --qq ssyyss Gets a copy of the current kernel sources, including the entire kernel directory hierarchy. The --qq option suppresses the message displayed as each directory is descended. eexxaammppllee%% ccvvss cchheecckkoouutt --pp --qq --ff --rrSSuunnOOSS ssyyss Gets an _e_x_a_c_t copy of the current revision SunOS kernel sources. The --ff option forces only files that have the ``SunOS'' tag to be retrieved, not including files locally added to the kernel sources. The --pp option prunes empty directories, thereby not including directories that have been locally added to the kernel source hierarchy. eexxaammppllee%% ccvvss cchheecckkoouutt --pp --DD ''AAuugguusstt 1100,, 11998899 1144::4400'' ssyyss The exact copy of the kernel sources as of the specified date and time is retrieved. The date is a free-form strings, as specified in rrccss(l). eexxaammppllee%% ccvvss ddiiffff --cc eexxaammppllee%% ccvvss ccoommmmiitt --aa --mm ''ffiixxeedd NNUULLLL ppooiinntteerr ddeerreeffeerreennccee'' The ddiiffff command displays a context diff of all the changes that you have made to the sources within the current direc- tory. Only those files thaty you have changed are displayed. The ccoommmmiitt command makes these changes permanent within the source repository so that others can benefit from your fix. eexxaammppllee%% ccvvss ddiiffff --cc --rrSSuunnOOSS ffiillee..cc eexxaammppllee%% ccvvss ddiiffff --cc --rr11..99 --rr11..1111 ffiillee..cc eexxaammppllee%% ccvvss ddiiffff --cc --rr11..2222 ffiillee..cc Examples of how the ddiiffff command can be used. The first example displays the differences between the SunOS version Sprite v1.0 20 July 1989 17 CVS UNKNOWN MANUAL SECTION CVS of the file and your checked out version. The second exam- ple shows the differences between two specific revisions of the RCS file. The final example diffs the currently checked out file against a specific revision of the RCS file. eexxaammppllee%% ccvvss ttaagg PPrriissmmaaOOSS11__00 ccsshh eexxaammppllee%% ccvvss ttaagg PPrriissmmaaOOSS11__00 bbiinn eexxaammppllee%% ccvvss ttaagg tteesstt__kkeerrnneell ssyyss eexxaammppllee%% ccvvss ttaagg --dd tteesstt__kkeerrnneell ssyyss eexxaammppllee%% ccvvss ttaagg --qq --ff --rrSSuunnOOSS SSUUNNOOSS .. eexxaammppllee%% ccvvss ttaagg --DD ''JJuunnee 3300,, 11998899'' JJUUNNEE__KKEERRNNEELL ssyyss FFIILLEESS CVS.adm A directory created by the cchheecckkoouutt command within each directory that contains checked out source files. This directory holds all the ccvvss administration files for an individual's private copy of the sources. In general, these files should not be edited by hand. ccvvss will do that for you. Be sure to _n_e_v_e_r remove this directory if you have source files that have been modified and need to be committed in the directory that the CVS.adm directory administrates. The files contained in this directory are described below. CVS.adm/Entries Contains the list of files that have been checked out in the current directory along with the revision number that each checked out file is up-to-date with and a timestamp that is used to quickly determine if a file has been possibly modified or not. CVS.adm/Entries.Backup A backup of the previous CVS.adm/Entries file, just in case of catastrophe. CVS.adm/Entries.Static The existence of this file tells ccvvss to only use the files contained in the CVS.adm/Entries file when gen- erating the list of source files for this directory. This allows selected files from a directory in the source repository to be checked out and manipulated without requiring that the entire source directory be used. CVS.adm/Mod After doing an uuppddaattee command, this file reflects the current list of modified source files for the direc- tory. Sprite v1.0 20 July 1989 18 CVS UNKNOWN MANUAL SECTION CVS CVS.adm/Repository Holds the pathname to the respective directory in the source repository that these files refer to. This is usually a relative pathname, with the value of the CVSROOT environment tacked on the front to produce a full pathname. If the pathname in the CVS.adm/Repository file is already a full pathname, the CVSROOT value is not tacked on. CVS.adm/Checkin.prog Contains one line which specifies the program that is to be run when any files in the current directory are checked in to the source repository with the ccoommmmiitt command. The particular use of this is to rebuild the ``modules'' database after a new revision is checked in - see mmkkmmoodduulleess(l). The following files or directories are created directly in the source repository directories as needed. CVSROOT.adm A directory that should exist in the top-most directory as defined by the CVSROOT environment variable. This directory contains administrations files that define the global actions for the entire source repository beginning at CVSROOT . The files used directly by ccvvss in this directory are described below, though you are free to add others as you see fit. CVSROOT.adm/modules,v The RCS file which defines the _m_o_d_u_l_e_s supported within this source repository. The format is as specified in the MMOODDUULLEE SSUUPPPPOORRTT section above for more information. CVSROOT.adm/loginfo,v The RCS file that contains the descriptions of which programs to pipe log messages into when ccoommmmiittting files. See the LLOOGGGGIINNGG SSUUPPPPOORRTT section above for more information. Attic When RCS files are removed with the rreemmoovvee command, the actual RCS file is moved into the Attic directory where it will remain until someone uses the aadddd command to restore it as a needed source file. #cvs.lock A lock directory created by ccvvss when doing sensitive changes to the RCS source repository. #cvs.tfl._p_i_d A lock file created just to test the waters of the RCS Sprite v1.0 20 July 1989 19 CVS UNKNOWN MANUAL SECTION CVS source repository directory before committing files. #cvs.rfl._p_i_d A read lock created when doing the uuppddaattee command. A ccoommmmiitt done by some other user will wait until all readers have finished using the directory before proceeding. #cvs.wfl._p_i_d A write lock created by ccoommmmiitt to cause any other uuppddaattees in the same source repository directory to block until the commit has completed. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS CVSROOT Must be set for most commands. Should contain the full pathname to the root of the ccvvss source repository, that is, where the RCS files are kept. CVSREAD If this is set, cchheecckkoouutt and uuppddaattee will try hard to make your private checked out sources read-only. When this is not set, the default behaviour is to make read-write files. RCSBIN Specifies the full pathname where to find RCS programs, such as ccoo(l) and ccii(l). If not set, the default is //uussrr//llooccaall//bbiinn. EDITOR Specifies the editor to use when doing a ccoommmmiitt. If not set, the default editor used is //uussrr//uuccbb//vvii. AAUUTTHHOORRSS Dick Grune Original author of the ccvvss shell script version posted to ccoommpp..ssoouurrcceess..uunniixx in the volume6 release of December, 1986. Credited with much of the ccvvss conflict resolution algorithms. Brian Berliner Coder and designer of the ccvvss program itself in April, 1989, based on the original work done by Dick. Jeff Polk Helped Brian with the design of the ccvvss module and ven- dor branch support and author of the cchheecckkiinn(l) shell script. SSEEEE AALLSSOO cchheecckkiinn(l), ccii(l), ccoo(l), ddiiffff(1), ggrreepp(1), mmkkmmoodduulleess(l), Sprite v1.0 20 July 1989 20 CVS UNKNOWN MANUAL SECTION CVS nnddbbmm(3), ppaattcchh(l), rrccss(l), rrccssddiiffff(l), rrccssmmeerrggee(l), rrlloogg(l), rrmm(1), ssoorrtt(1). BBUUGGSS Sprite v1.0 20 July 1989 21